home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
FishMarket 1.0
/
FishMarket v1.0.iso
/
fishies
/
626-637
/
disk_627
/
adoc
/
adocenglish.doc
< prev
next >
Wrap
Text File
|
1992-05-06
|
22KB
|
549 lines
ADoc v7.04 - User's guide
This file describes release 7.04 of the utility ADoc. This program
is public domain, and permission is granted to freely distribute and copy
it, provided no charge or fee is ask for, and no modification is done to
this package.
ADoc is copyright (c)1990-1991-1992 by Denis GOUNELLE, any
commercial usage or selling of this program, without written authorization,
is ABSOLUTLY FORBIDEN. By mutual agreement, Serge HAMMOUCHE is authorized
to distribute ADoc as he likes.
"PowerPacker 2.3b" is (c)1989 by PowerPeak and Nico FRANCOIS.
"PowerPacker Pro 3.0b" is (c)1990 by PowerPeak and by UGA Software. The
"powerpacker.library" library is (c)1990 by Nico FRANCOIS. AREXX is
(c)1987 by Bill Hawes.
No warranty is made that there's no errors in this program. YOU
USE THIS PROGRAM AT YOUR OWN RISKS. In no event will I be liable for any
damage, direct or indirect, resulting of the use of ADoc.
Table of contents:
------------------
1. Introduction
2. How does it work.
3. User's guide
3.1 Running ADoc from the CLI.
3.2 Running ADoc from the WorkBench.
3.3 User's guide.
3.4 The term request.
4. Advanced concepts
4.1 Using several documentation files.
4.2 How to rely several files to a documentation file.
4.3 How to create several indexes.
4.4 How to extend the character set.
4.5 Using "powerpacker.library".
4.6 The AREXX mode.
4.7 Using Commodore AutoDoc files.
4.8 The "Special" menu.
5. Error messages.
1. Introduction.
----------------
ADoc is an utility that allows you to manage all kinds of
documentation files. Its major feature is automatic search for a word
selected by a mouse click. Also, ADoc can work on several documentation
files at the same time, on Commodore AutoDoc files, and has an AREXX port.
+--------------------------------------------------------+
| CAUTION !!! |
| |
| The doc file format has changed from releases 3.xx and |
| 4.xx to releases 5.xx. To make old doc files work read |
| the documentation file to know what is the new format, |
| modify your old docs (this should not take you lots of |
| time...) and re-create the index files. |
+--------------------------------------------------------+
You can send me your suggestions or criticism writing to:
M. GOUNELLE Denis
Boite 71
6, rue des cailloux
92110 CLICHY - FRANCE
Many thanks to Jean-Yves PROUX, Jean-Philippe RAPP and Helmut J.
ESENWEIN for their numerous suggestions, to Simon HEWINSON for the english
translation of the "Amiga.doc" file. Thanks again to Jean-Philippe RAPP
for gaving me the opportunity to test ADoc with 2.02 release AutoDoc
files.
2. How does it work.
--------------------
ADoc works on a documentation file created with a text editor.
This file will contain a list of terms and each term will look like this:
term
explanation line 1
explanation line 2
. . .
. . .
explanation line n
The first character of each term MUST be at column 1, and the
explanation lines MUST begin at least with a space or a tab character.
It's the only way ADoc can make a distinction between a term and its
explanation. Also, the first and second line of the documentation file
MUST be empty (or begin with a space or tab character, for more
informations see sections 4.2 and 4.4).
The term string can't be more than 32 characters long and can't
contain any spaces or tabs. The following are valid characters: single
letters (upper or lower case), digits, stressed lowercase letters (ASCII
codes between 217 and 246) and underline. However, you can extend this
character set (see section 4.4).
ADoc won't complain if a term is defined several times in a file :
the explanation lines will just be put together when the text for this
term will have to be displayed. If you define the term "AboutThisDoc", the
corresponding text will automatically be displayed at startup time.
You can't use more than 32767 terms for each documentation file.
An explanation line can't be more than 256 characters long (however, only
the first characters will be displayed). The number of explanation lines
for a term is unlimited.
You can include the following ANSI sequences in your explanation
lines:
ESC[0m Normal character set
ESC[1m Boldface on
ESC[3m Italics on
ESC[22m Boldface off
ESC[23m Italics off
Once the documentation file has been created, ADoc will built an
index file allowing to access a term almost instantly. The name of this
index file will be the documentation file name plus an ".index" suffix.
+-------------------------------------------------------+
| CAUTION !!! |
| |
| You MUST re-build your index file each time you |
| modify the documentation file. |
+-------------------------------------------------------+
3. User's guide.
----------------
ADoc can be run from WorkBench or from the CLI. By default, the
documentation file is "Amiga.doc", but in both cases you can specify
another filename.
3.1 Running ADoc from CLI.
--------------------------
From the CLI, ADoc is invoked using a command line of the form:
ADoc -i [-f<file>]
or ADoc [-c][-e][-f<file>][-l][-n][-q][-A][<term>]
The first command line invokes ADoc for creating a documentation
file index; the second one allows to interrogate the documentation file.
Five options are avalaible:
-i if specified, ADoc only creates the documentation file
index. This option MUST be the first one in the command
line.
-c tells ADoc to ignore letter case (in search as well as
in term request). Should be specified before any -f
option.
-e if specified, ADoc opens its own screen, instead of
using the Workbench's screen. Please take notice that
ADoc always open its own screen when WorkBench's screen
default font is not "topaz8".
-f<file> if specified, ADoc look for this documentation file. If
no full pathname was specified, ADoc looks for the file
first in the current directory, and then in the "ADOC:"
directory.
-l if specified, ADoc opens a screen in interlaced mode.
If you didn't specify -e option, and your Workbench's
screen is not in interlaced mode, ADoc will open its
own screen.
-n asks ADoc to don't sort index when displaying term
request. Should be specified before any -f option.
-q asks ADoc to don't display "AboutThisDoc" term at
startup time.
-A if specified, sets AREXX mode (see section 4.6). The
-i and -e options can't be used with this option.
When using the second command line, you can specify a term of the
documentation file to be searched first (optional).
3.2 Running ADoc from Workbench.
--------------------------------
From Workbench, ADoc is inwoked by four ways :
- by double-clicking on its icon (then ADoc will use the default
documentation file)
- by clicking on a documentation file icon which default tool is
ADoc.
- by clicking on ADoc icon, holding down the SHIFT key, and then
double-clicking on a documentation file icon
- by clicking on a documentation file icon, holding down the
SHIFT key, and double-clicking on ADoc icon.
When ADoc is run from the Workbench, it always opens its own
screen. You can specify options in the "TOOL TYPES" field of ADoc icon, or
file icon. The syntax is :
ADOC=[INTERLACE]|[NOSORT]|[CASE]|[QUICK]
The INTERLACE parameter asks for a screen in interlace mode. The NOSORT
parameter asks ADoc to don't sort index when displaying term request. The
CASE parameter tells ADoc to ignore letter case when searching, or in term
request. The QUICK parameter asks ADoc to don't display the "AboutThisDoc"
term at startup time.
3.3 User's guide.
-----------------
When opening the help file, ADoc searchs for the "AboutThisDoc"
term. If it exists, the corresponding text is displayed in a window and
ADoc waits for this window to be closed to continue.
If ADoc was invoked either from Workbench, or from CLI and the
term was not specified in the command line, the program displays a
requester with a list of the known terms. See section 3.4 for term request
description.
When you have specified the term to search, a window will appear
with the text corresponding to the term. If the text is too large to be
fully displayed, only the first page will be displayed, and two arrow
gadgets will apeared on the title bar of the window. These gadgets allow
to move your text in the window, and will be automatically added or
removed if required when the window is resized. To close the window, click
on the close gadget or press the ESCAPE key.
Now, you can click twice on a word of the explanation text: that
will run the searching function for this word automatically. If the word
couldn't be found the screen will flash, otherwise the text will be
displayed in a new window.
If you want to get the text for a term, and this term is not is
any displayed text, you need to select the "Other term" command from the
"Project" menu: ADoc will display a requester with the list of known terms
within (see section 3.4 for term request description).
In both cases, if you selected a term relied to a window, this
window will be put in the foreground.
You can print the text relied to a term by selecting the "Print"
command from the "Project" menu. In the eventuality your text has some
escape sequences, these will (of course) be correctly interpreted by the
printer.
You can iconify ADoc by selecting the "Iconify" command from the
"Project" menu. Then, all the windows will be closed (if ADoc opened its
own screen, it will be closed too) and a small window will appear on the
left top corner of the Workbench's screen. Now, either you can quit ADoc
by clicking on the window close gadget, or you can awake it by pressing
the right mouse button. At this moment, ADoc will suggest you to 're-open'
all the windows that were opened when you have iconified it. By selecting
"NO" you'll get the term request.
You can move ADoc from a screen to another one by selecting the
"Front Screen" command from the Project menu. To do it, move the screen
where you want ADoc to display in front of all the other screens, drag it
down and move ADoc screen just behind. Choose now the "Front Screen"
command: all the windows will be moved to the foreground screen. Please
take notice that this command won't work if default font of destination
screen is not "topaz8", or if ADoc screen is in interlace mode while
destination screen doesn't.
You can quit ADoc either by closing each window (ADocs stops when
the last window is closed) or by choosing the "Quit" command from the
Project menu.
When a YES/NO requester is displayed, you can answer "YES" by
pressing the RETURN key, or answer "NO" by pressing the ESCAPE key.
3.4 The term request
--------------------
The term request allows you to select a term with your mouse. If
you click on a term, this term will be (red) highlightened. Click once
again on it to confirm your choice, or click on another term if you
changed your mind.
You can also make your choice with the keyboard. If you press a
key, this letter will be added to the current prefix (displayed in a box
at the bottom of the window), and the display of the term list will start
with the first term beginning with this prefix. ADoc will try to complete
the prefix as far as possible. If you press the BACKSPACE key, the last
letter of the prefix will be removed, and the display updated. If you
press the RETURN key, the first term corresponding to the prefix will be
taken as your choice. If you press the ESCAPE key, the window will be
closed and the request aborted.
4. Advanced concepts.
---------------------
4.1 Using several documentation files.
--------------------------------------
To do it, only you need to specify the names of the files you want
to use: from Workbench, by selecting the icon of these files, from the CLI
by typing a comand line of the form:
ADoc [options] -fname1,name2,...nameN [<term>]
You can specify several -f options and other options between them,
like :
ADoc -fname1,name2 -c -fname3 -n -fname4
which cause ADoc to load name1, name2, name3 and name4 files. The index of
name1, name2 and name3 files will be sorted in the term request (ignoring
letter case for name3 file), but not the index of name4 file.
If you don't specify the full path name for a file, it is supposed
to be in the current directory or in the "ADOC:" directory. By specifying
a directory name (or, from Workbench, by selecting a directory icon), all
the files of this directory will be used (except files whose filename
extension is ".info" or ".index"). As usual, when one or several index
files don't exist, Adoc will ask for creating them.
Practically, ADoc works as usual. Here is additional features:
- when opening EACH file, ADoc will search for the
"AboutThisDoc" term and display the corresponding text,
then wait for the window to be closed to continue.
- ADoc looks for a selected word in ALL documentation files it
is using
- if a term is defined in several files, all the lines will be
put together and displayed in the same window
- when ADoc displays a requester, you can change the "display"
by pressing on the right mouse button: alternately, you'll
get either the list of terms of the current documentation
file, or a list of files that ADoc is using at this moment.
So, you can select a term in any documentation file.
ADoc won't load twice the same file. Two files are considered as
identical EITHER if their names are identical OR if their indexes have
been created at the same date and time. Date value is stored in the index
file when you created it, so this value will change only if you re-create
this index file.
4.2 How to rely several files to a documentation file.
------------------------------------------------------
Also, it's possible for you to connect one or more files to a
documentation file. In this case, when this documentation file is opened,
automatically, at the same time, ADoc will load the relied files.
To use this function, only you need to specify the name of every
file you want to rely to the documentation file, separated with commas, in
the first line of this file. If the first command line is empty, or begins
by a space or tab character, no file will be relied to the doc file.
Except if you specify a full path name, ADoc will search for the
associated files first in the current directory, then in the "ADOC:"
directory. If you specified a directory, every file in this directory
will be be associated to the documentation file (except files whose
filename extension is ".info" or ".index").
4.3 How to create several indexes.
----------------------------------
You can specify several files even when you are using -i option,
e.g. the command line will look like this:
ADoc -i -fname1,name2,...nameN
In this case, ADoc will create an index for every file you
specified, then it stops.
4.4 How to extend the character set.
------------------------------------
Sometimes, it would be useful to extend the character set to use
in a term. The second line of a doc file is reserved for this use. If this
line doesn't begin neither with a space nor with a tab character, all the
characters of this line will be added to the allowed set until ADoc reads
one of the following character : space, tab, newline, form-feed, slash.
Note that this extension is made separately for every file. This
means that if you are using several doc files simultaneously, the allowed
characters will change from a file to another, according with those you
specified in the second line of every file.
4.5 Using "powerpacker.library".
--------------------------------
ADoc can load any files compressed with "PowerPacker 2.3b" or with
"PowerPacker Pro 3.0b", according you have set up "powerpacker.library" in
the "LIBS:" directory of your hard disk or floppy disk.
Index file doesn't need to be created before compression. ADoc
will refuse to load an encrypted file.
After ADoc has uncompressed the file, it will be copied in a
temporary file in the "T:" directory. This temporary file will be deleted
at the end of working session. Using compressed files can require a lot of
memory (especially if you put the "T:" directory in your RAM: disk), so
I suggest you to compress several "little" files (30 to 50 Kb) rather than
one big file (more than 100 Kb).
4.6 The AREXX mode.
-------------------
If you specify -A option when calling ADoc, you'll get the AREXX
mode: an AREXX compatible message port named "ADoc_rexx" is opened, and
ADoc waits for messages on this port. You can't specify -e nor -i options
whith the -A option.
Note that ADoc won't be able to go in AREXX mode when it have to
open it's own screen, so you can't specify -e option with -A option. Also,
if ADoc is run from WorkBench, or if you specify -l option and the
WorkBench screen is not in interlaced mode, the AREXX mode will be
silently disabled.
The messages can be :
quit : ADoc closes the message port and terminates.
wakeup : ADoc closes the message port and goes to normal
Intuition mode.
?term : ADoc searches this term, and if found, goes to normal
Intuition mode to display the corresponding text.
Any other message will be ignored.
Here comes an example of AREXX program, that ask for help on
"alias" and terminate ADoc :
/* Ask for help on "alias" */
address "ADoc_rexx"
"?alias"
"quit"
Please note the " characters arround commands !
In normal Intuition mode, you can go to AREXX mode with the "AREXX
mode" command in Project menu: all opened windows will be closed, and ADoc
will wait for messages on it's port.
When you use ADoc in AREXX mode, don't forget that ADoc will go
back from normal Intuition mode to AREXX mode when you close the last
opened window. To terminate ADoc, use the "Quit" command in Project menu.
4.7 Using Commodore AutoDoc files.
----------------------------------
This release of ADoc is able to recognize and use Commodore
AutoDoc files. In most cases, you won't have to modify these files, but
you should verify their format : there must be at least two empty lines at
the top of the file, and each term must start in column 1.
You will find, sometimes, that the empty lines are missing and
that each term is preceded by a "form-feed" (CTRL-L) character. The
AutoConvert programm (included in ADoc distribution) will automatically
convert such files in the good format (NOTE: AutoConvert must be used from
CLI only). In any other case, you will have to modify the files by
yourself.
ADoc has been tested with the 45 AutoDoc files for system release
2.02 : 27 didn't need any modification, 11 needed to be converted by
AutoConvert, and the remaining 7 had to be hand-modified.
4.8 The "Special" menu.
-----------------------
The "Info" item will tell you how much files, terms, windows and
lines are available.
The "Open file" item allows you to open a new doc file at any
time. A file requester will appear, so you will be able to select the file
to open. The files which names end by ".info" or ".index" are hidden.
Click on "ABORT" or close the window to abort.
The "Close file" item allows you to close a doc file you don't
need, in order to free some memory. You will be asked for confirmation but
remember that you'll always be able to open it again with the "Open file"
item.
The "Close windows" item allows you to close all the help windows
opened at the current time. You will be asked for confirmation, and the
term requester will appear after all windows have been closed.
5. Error messages.
------------------
I've put the section where you will find more information on error
message in brackets.
- Bad arguments (3.1)
Error in command line.
- Can't open <name>
Ressource <name> couldn't be opened.
Ressource can be a documentation file (verify if this file does
exist) or an index file (see sections 3.1 and 3.3 to create it).
- Line too long <line> (see section 2.)
The indicated line is more than 256 characters long.
- Term too long <name> (see section 2.)
The specified term is more than 32 characters long.
- No text for <term> (see section 2.)
No explanation line for this term.
- Empty file <name>
The file you specified is empty, or no term was found in this
file.
- Read error <name>
An error occurred while ADoc was reading this file.
- Write error <name>
An error occurred while ADoc wrote this file.
- Bad index file <name> (see sections 2., 3.1 and 3.3)
The index file you specified is incorrect. You MUST re-create
it.
- Bad association for <name> (see section 4.2)
The first line this file (the line that gives you a list of all
the relied files) is wrong or incorrectly spelt.
- Crypted file <name> (see section 4.5)
The file you specified was crypted with PowerPacker.